home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997…eptember: Technology Seed / ATS Aug-Sept '97.toast / Navigation Services SDK / Interfaces / CIncludes / Navigation.h
Encoding:
C/C++ Source or Header  |  1997-08-18  |  15.7 KB  |  453 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        Navigation.h
  3.  
  4.     Copyright:    © 1992, 1995-1997 by Apple Computer, Inc., all rights reserved.
  5.  
  6. */
  7.  
  8. #ifndef __NAVIGATION__
  9. #define __NAVIGATION__
  10.  
  11. #ifndef __APPLEEVENTS__
  12. #include <AppleEvents.h>
  13. #endif
  14.  
  15. #ifndef __TRANSLATION__
  16. #include <Translation.h>
  17. #endif
  18.  
  19. #ifndef __WINDOWS__
  20. #include <Windows.h>
  21. #endif
  22.  
  23. #ifndef __CODEFRAGMENTS__
  24. #include <CodeFragments.h>
  25. #endif
  26.  
  27. #ifdef __cplusplus
  28. extern "C" {
  29. #endif
  30.  
  31. #if PRAGMA_IMPORT_SUPPORTED
  32. #pragma import on
  33. #endif
  34.  
  35. #if PRAGMA_ALIGN_SUPPORTED
  36. #pragma options align=mac68k
  37. #endif
  38.  
  39.  
  40. /* Navigation Services Error Codes: */
  41. enum {
  42.     missingKindStringErr            = -5699,
  43.     invalidCustomControlMessageErr     = -5698
  44. };
  45.  
  46. enum {
  47.     kNavDialogaOptionsVersion = 0,
  48.     kNavReplyRecordVersion = 0,
  49.     kNavCBRecVersion = 0,
  50.     kNavFileOrFolderVersion = 0,
  51.     kNavMenuItemSpecVersion = 0
  52. };
  53.  
  54. /* values for the "action" parameter of NavAskSaveChanges: */
  55. enum {
  56.     kNavSaveChangesClosingDocument         = 1,    /* closing a document */
  57.     kNavSaveChangesQuittingApplication     = 2,    /* quitting the application */
  58.     kNavSaveChangesOther                = 0        /* neither closing nor quitting */
  59. };
  60. typedef UInt32 NavAskSaveChangesAction;
  61.  
  62.  
  63. /* return values from NavAskSaveChanges, NavCustomAskSaveChanges: */
  64. enum {
  65.     askSaveChangesSave            = 1,
  66.     askSaveChangesCancel        = 2,
  67.     askSaveChangesDontSave        = 3
  68. };
  69. typedef UInt32 NavAskSaveChangesResult;
  70.  
  71.  
  72. /* return values from NavAskDiscardChanges: */
  73. enum {
  74.     askDiscardChanges            = 1,
  75.     askDiscardChangesCancel        = 2
  76. };
  77. typedef UInt32 NavAskDiscardChangesResult;
  78.  
  79.  
  80. /* NavFileInfo is the part of NavFileOrFolderInfo for files: */
  81. struct NavFileInfo {
  82.     Boolean             locked;            /* file is locked */
  83.     Boolean             resourceOpen;    /* resource fork is opened */
  84.     Boolean             dataOpen;        /* data fork is opened */    
  85.     Boolean             reserved;
  86.     UInt32                 dataSize;        /* size of the data fork */
  87.     UInt32                 resourceSize;    /* size of the resource fork */
  88.     FInfo                 finderInfo;        /* more file info: */
  89.     FXInfo                 moreFinderInfo;
  90. };
  91. typedef struct NavFileInfo NavFileInfo;
  92.  
  93. /* NavFolderInfo is the part of NavFileOrFolderInfo for folders and volumes: */
  94. struct NavFolderInfo {
  95.     Boolean             shareable;
  96.     Boolean             sharePoint;
  97.     Boolean             mounted;
  98.     Boolean             readable;
  99.     Boolean             writeable;
  100.     Boolean             reserved;
  101.     UInt32                 numberOfFiles;
  102.     DInfo                 finderInfo;
  103.     DXInfo                 moreFinderInfo;
  104. };
  105. typedef struct NavFolderInfo NavFolderInfo;
  106.  
  107. /* NavFileOrFolderInfo is the structure passed to your filter proc for typeFSS AEDescs: */
  108. struct NavFileOrFolderInfo {
  109.     UInt16                version;
  110.     Boolean             isFolder;
  111.     Boolean             visible;
  112.     UInt32                creationDate;
  113.     UInt32                modificationDate;
  114.     union {
  115.         NavFileInfo     fileInfo;
  116.         NavFolderInfo     folderInfo;
  117.     }                     u;
  118.         char                reserved[256];
  119. };
  120. typedef struct NavFileOrFolderInfo NavFileOrFolderInfo;
  121.  
  122.  
  123. /* =============================================================================================== */
  124. /* navigation event/callback information: */
  125.  
  126. typedef UInt32 NavContext;
  127.  
  128. struct NavCBRec {    
  129.     UInt16                version;
  130.     NavContext            context;        /* used by customization code to call Navigation Services */
  131.     WindowPtr            window;            /* the dialog */
  132.     Rect                customRect;        /* local coordinate rectangle of customization area */
  133.     Rect                previewRect;    /* local coordinate rectangle of the preview area */
  134.     union {
  135.         EventRecord*    event;            /* for event processing */
  136.         void*            param;            /* points to event specific data */
  137.     #ifndef __cplusplus
  138.     }                     u;
  139.     #else
  140.     };
  141.     #endif
  142.     char                reserved[256];
  143. };
  144.  
  145. typedef struct NavCBRec NavCBRec;
  146. typedef NavCBRec *NavCBRecPtr;
  147.  
  148. enum {
  149.     kNavCBEvent,            /* an event has occurred (update, idle events, etc.) */
  150.     kNavCBCustomize,        /* protocol for negotiating customization space */
  151.     kNavCBStart,            /* the navigation dialog is starting up */
  152.     kNavCBTerminate,        /* the navigation dialog is closing down */
  153.     kNavCBAdjustRect,        /* the navigation dialog is being resized */
  154.     kNavCBNewLocation,        /* user has chosen a new location in the browser */
  155.     kNavCBShowDesktop,        /* user has navigated to the desktop */
  156.     kNavCBSelectEntry,        /* user has made a selection in the browser */
  157.     kNavCBPopupMenuSelect    /* signifies that a popup menu selection was made */
  158. };
  159. typedef SInt32 NavEventCallbackMessage;
  160.  
  161. typedef UInt32 NavCallBackUserData;
  162.  
  163. /* for events and customization: */
  164. typedef pascal void (*NavEventProcPtr) (     const NavEventCallbackMessage callBackSelector, 
  165.                                             NavCBRecPtr callBackParms, 
  166.                                             NavCallBackUserData callBackUD );
  167. /* for preview support: */
  168. typedef pascal Boolean (*NavPreviewProcPtr) (     NavCBRecPtr callBackParms, 
  169.                                                 NavCallBackUserData callBackUD );                        
  170.  
  171. /* filtering callback information: */
  172. typedef pascal Boolean (*NavObjectFilterProcPtr) (     AEDesc* theItem, 
  173.                                                     void* info, 
  174.                                                     NavCallBackUserData callBackUD );
  175.  
  176.                                                     
  177. #if GENERATINGCFM
  178. typedef UniversalProcPtr NavEventProcUPP;
  179. typedef UniversalProcPtr NavPreviewProcUPP;
  180. typedef UniversalProcPtr NavObjectFilterProcUPP;
  181. #else
  182. typedef NavEventProcPtr NavEventProcUPP;
  183. typedef NavPreviewProcPtr NavPreviewProcUPP;
  184. typedef NavObjectFilterProcPtr NavObjectFilterProcUPP;
  185. #endif
  186.  
  187. enum {
  188.     uppNavEventProcInfo = kPascalStackBased
  189.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(NavEventCallbackMessage)))
  190.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(NavCBRecPtr)))
  191.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(NavCallBackUserData)))
  192.          ,
  193.     uppNavPreviewProcInfo = kPascalStackBased
  194.          | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
  195.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(NavCBRecPtr)))
  196.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(NavCallBackUserData)))
  197.          ,
  198.     uppNavObjectFilterProcInfo = kPascalStackBased
  199.          | RESULT_SIZE(SIZE_CODE(sizeof(Boolean)))
  200.          | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(AEDesc*)))
  201.          | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(void*)))
  202.          | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(NavCallBackUserData)))
  203. };
  204.  
  205.  
  206. #if GENERATINGCFM
  207. #define NewNavEventProc(userRoutine)        \
  208.         (NavEventProcUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavEventProcInfo, GetCurrentArchitecture())
  209. #define NewNavPreviewProc(userRoutine)        \
  210.         (NavPreviewProcUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavPreviewProcInfo, GetCurrentArchitecture())
  211. #define NewNavObjectFilterProc(userRoutine)        \
  212.         (NavObjectFilterProcUPP) NewRoutineDescriptor((ProcPtr)(userRoutine), uppNavObjectFilterProcInfo, GetCurrentArchitecture())
  213. #else
  214. #define NewNavEventProc(userRoutine)        \
  215.         ((NavEventProcUPP) (userRoutine))
  216. #define NewNavPreviewProc(userRoutine)        \
  217.         ((NavPreviewProcUPP) (userRoutine))
  218. #define NewNavObjectFilterProc(userRoutine)        \
  219.         ((NavObjectFilterProcUPP) (userRoutine))
  220. #endif
  221.  
  222.  
  223. /* =============================================================================================== */
  224. /* custom control information: */
  225.  
  226. enum {
  227.     kNavCtlShowDesktop,            /*    show desktop,                 parms==nil */
  228.     kNavCtlShowFavorite,        /*    show favorites,             parms==nil */
  229.     kNavCtlShowRecent,            /*    show recents,                parms==nil */
  230.     kNavCtlSortBy,                /*    sort key field,             parms->NavSortKeyField */
  231.     kNavCtlSortOrder,            /*    sort order,                    parms->NavSortOrder */
  232.     kNavCtlScrollHome,            /*    scroll list home,            parms==nil */
  233.     kNavCtlScrollEnd,            /*    scroll list end,            parms==nil */
  234.     kNavCtlPageUp,                /*    page list up,                parms==nil */
  235.     kNavCtlPageDown,            /*    page list down,                parms==nil */
  236.     kNavCtlGetLocation,            /*    get current location,        parms->AEDesc (filled in) */
  237.     kNavCtlSetLocation,            /*    set current location,        parms->AEDesc */
  238.     kNavCtlGetSelection,        /*    get current selection,        parms->AEDesc (filled in) */
  239.     kNavCtlSetSelection,        /*    set current selection,        parms->AEDesc */
  240.     kNavCtlShowSelection,        /*    make selection visible,        parms==nil */
  241.     kNavCtlOpenSelection,        /*    open view of selection,        parms==nil */
  242.     kNavCtlEjectVolume,            /*    eject volume,                parms->vRefNum */
  243.     kNavCtlNewFolder,            /*    create a new folder,        parms==StringPtr (Str31) */
  244.     kNavCtlCancel,                /*    cancel dialog,                parms==nil */
  245.     kNavCtlAccept,                /*    accept dialog default,        parms==nil */
  246.     kNavCtlIsPreviewShowing,    /*    query preview status,        parms->Boolean */
  247.     kNavCtlAddControls,            /*    add custom controls            parms->Handle (DITL list) */
  248.     kNavCtlGetFirstControlID    /*    get 1st control ID,            parms->UInt32 */
  249. };
  250. typedef SInt32 NavCustomControlMessage;
  251.  
  252.  
  253. /* browser sort keys: */
  254. enum {
  255.     kNavSortNameField,
  256.     kNavSortSizeField,
  257.     kNavSortDateField
  258. };
  259. typedef UInt16 NavSortKeyField;
  260.  
  261. /* browser sort orders: */
  262. enum {
  263.     kNavSortAscending,
  264.     kNavSortDescending
  265. };
  266. typedef UInt16 NavSortOrder;
  267.  
  268.                                     
  269. /* =============================================================================================== */
  270.  
  271. /* dialog options and features: */
  272. enum {
  273.     kDefaultNavDlogOptions    = 0x00000000,        /*    use defaults for all the options */
  274.     kNoTypePopup            = 0x00000001,        /*    don't show file type/extension popup on Open/Save */
  275.     kDontAutoTranslate        = 0x00000002,        /*    don't automatically translate on Open */
  276.     kDontAddTranslateItems    = 0x00000004,        /*    don't add translation choices on Open/Save */
  277.     kExtendPopup            = 0x00000008,        /*    extend translation choices on Open/Save */
  278.     kAllFilesInPopup        = 0x00000010,        /*    "All Files" menu item in the type popup on Open */
  279.     kAllowStationery        = 0x00000020,        /*    allow saving of stationery files */
  280.     kNavDialogOptionsUnused = 0xFFFFFFFF
  281. };
  282. typedef UInt32 NavDialogOptionFlags;
  283.  
  284.  
  285. /* 'open' resource data format: */
  286. struct OpenResource {
  287.     OSType            componentSignature;
  288.     short            reserved;
  289.     short            osTypeCount;
  290.     OSType            osType[1];
  291. };
  292. typedef struct OpenResource OpenResource, **OpenResourceHandle;
  293.  
  294.  
  295. /* options to designate how file(s) will be translated by NavTranslateFile(): */
  296. enum {
  297.     kNavTranslateInPlace = 0,        /*    translate in place, replacing translation source file (default for Save) */
  298.     kNavTranslateCopy                /*    translate to a copy of the source file (default for Open) */
  299. };
  300. typedef UInt32 NavTranslationOptions;
  301.  
  302.  
  303. /* definition for each menu item added to the open/save dialog's popup menu: */
  304. struct NavMenuItemSpec {                
  305.     UInt16        version;    
  306.     OSType        creator;            /* the application's signature */
  307.     OSType        type;                /* data tag or file type */
  308.     Str255        menuItemName;
  309.     char        reserved[249];
  310. };
  311. typedef struct NavMenuItemSpec NavMenuItemSpec, **NavMenuItemSpecHandle;
  312.  
  313.  
  314. /* options for affecting the appearance of a tility dialog: */
  315. struct NavDialogOptions {    
  316.     UInt16                    version;    
  317.     NavDialogOptionFlags    dialogOptionFlags;        /* option flags for affecting the dialog's behavior */
  318.     Point                     location;                /* top-left location of the dialog, or {-1,-1} for default position */
  319.     Str63                    applicationName;        /* application string to display in dialog window title (or null string for default) */
  320.     Str31                     actionButtonLabel;        /* label of the default button (or null string for default) */
  321.     Str31                    cancelButtonLabel;        /* label of the cancel button (or null string for default) */
  322.     Str31                    savedFileName;            /* default name for text box in NavPutFile (or null string for default) */
  323.     Str63                    message;                /* custom message prompt (or null string for default) */
  324.     Boolean                    allowPreviews;            /* allow to show previews */
  325.     Boolean                    allowMultipleFiles;        /* allow multiple items to be selected */
  326.     Boolean                    allowInvisibleFiles;    /* allow invisible items to be shown */
  327.     Boolean                    dontResolveAliases;        /* don't resolve aliases */    
  328.     UInt32                    preferenceKey;            /* a key for to managing preferences for using multiple utility dialogs */
  329.     Handle                    popupExtension;            /* extended popup menu items, an array of NavMenuItemSpecs */        
  330.     char                    reserved[14];
  331. };
  332. typedef struct NavDialogOptions NavDialogOptions;
  333.  
  334.  
  335. /* =============================================================================================== */
  336. /* data returned by the utility dialogs: */
  337.  
  338. struct NavReplyRecord {
  339.     UInt16                    version;
  340.     Boolean                 validRecord;            /* open/save: true if the user confirmed a selection, false on cancel */
  341.     Boolean                 replacing;                /* save: true if the user is overwriting an existing object for save */
  342.     Boolean                    isStationery;            /* save: true if the user wants to save an object as stationery */
  343.     Boolean                    translationNeeded;        /* save: translation is 'needed', open: translation 'has taken place' */        
  344.     AEDescList                selection;                /* open/save: list of AppleEvent descriptors of the chosen object(s) */
  345.     ScriptCode                theScriptCode;            /* open/save: script in which the name of each item in 'selection' is to be displayed */
  346.     FileTranslationSpec        **fileTranslation;        /* open/save: list of file translation specs of the chosen object(s), if translation is needed */
  347.     char                    reserved[236];
  348. };
  349. typedef struct NavReplyRecord NavReplyRecord;
  350.  
  351.  
  352. /* =============================================================================================== */
  353.  
  354. extern pascal UInt32 NavLibraryVersion(void);    /* returns the current version of Navigation Services */
  355.  
  356. extern pascal OSErr NavGetDefaultDialogOptions(NavDialogOptions* dialogOptions);
  357.                                                 /* initializes and sets up the dialog options or features to the default state: */
  358.  
  359. extern pascal OSErr NavGetFile(    AEDesc* defaultLocation, 
  360.                                 NavReplyRecord* reply, 
  361.                                 NavDialogOptions* dialogOptions,
  362.                                 NavEventProcUPP eventProc,
  363.                                 NavPreviewProcUPP previewProc,
  364.                                 NavCallBackUserData callBackUD,
  365.                                 Handle openResource,
  366.                                 NavObjectFilterProcUPP filterProc );
  367.                                 
  368. extern pascal OSErr NavPutFile(    AEDesc* defaultLocation,
  369.                                 NavReplyRecord* reply, 
  370.                                 NavDialogOptions* dialogOptions,
  371.                                 NavEventProcUPP eventProc, 
  372.                                 NavCallBackUserData callBackUD,                                    
  373.                                 OSType fileType,
  374.                                 OSType fileCreator );
  375.  
  376. extern pascal OSErr NavAskSaveChanges(    StringPtr applicationName, 
  377.                                         StringPtr documentName, 
  378.                                         NavAskSaveChangesAction action, 
  379.                                         NavAskSaveChangesResult* reply,
  380.                                         NavEventProcUPP eventProc, 
  381.                                         NavCallBackUserData callBackUD );
  382.  
  383. extern pascal OSErr NavCustomAskSaveChanges(     StringPtr message, 
  384.                                                 NavAskSaveChangesResult* reply, 
  385.                                                 NavEventProcUPP eventProc, 
  386.                                                 NavCallBackUserData callBackUD );
  387.  
  388. extern pascal OSErr NavAskDiscardChanges(    StringPtr documentName,
  389.                                             NavAskDiscardChangesResult* reply,
  390.                                             NavEventProcUPP eventProc,
  391.                                             NavCallBackUserData callBackUD );
  392.                             
  393. extern pascal OSErr NavChooseFile(    AEDesc* defaultLocation,
  394.                                     NavReplyRecord* reply,
  395.                                     NavDialogOptions* dialogOptions,
  396.                                     NavEventProcUPP eventProc,
  397.                                     NavPreviewProcUPP previewProc,
  398.                                     NavCallBackUserData callBackUD,                                    
  399.                                     OSType fileType );
  400.                                         
  401. extern pascal OSErr NavChooseFolder(    AEDesc* defaultLocation,
  402.                                         NavReplyRecord* reply,
  403.                                         NavDialogOptions* dialogOptions,
  404.                                         NavEventProcUPP eventProc, 
  405.                                         NavCallBackUserData callBackUD );
  406.  
  407. extern pascal OSErr NavChooseVolume(    NavReplyRecord* reply,
  408.                                         NavDialogOptions* dialogOptions,
  409.                                         NavEventProcUPP eventProc, 
  410.                                         NavCallBackUserData callBackUD);
  411.                                                                          
  412. extern pascal OSErr NavNewFolder(    AEDesc* defaultLocation,
  413.                                     NavReplyRecord* reply,
  414.                                     NavDialogOptions* dialogOptions,
  415.                                     NavEventProcUPP eventProc, 
  416.                                     NavCallBackUserData callBackUD );
  417.                                                                 
  418. extern pascal OSErr NavTranslateFile( NavReplyRecord* reply, NavTranslationOptions howToTranslate );
  419.  
  420. extern pascal OSErr NavCompleteSave( NavReplyRecord* reply, NavTranslationOptions howToTranslate );
  421.  
  422. extern pascal OSErr NavCustomControl( NavContext context, NavCustomControlMessage selector, void* parms );
  423.  
  424. extern pascal OSErr NavDisposeReply( NavReplyRecord* reply );
  425.  
  426.  
  427. /* =============================================================================================== */
  428. /* Checking for library availability: */
  429.  
  430. #if GENERATINGCFM
  431. #if __cplusplus
  432. inline pascal Boolean NavServicesAvailable() { return NavLibraryVersion != (void*)kUnresolvedCFragSymbolAddress; }
  433. #else
  434. #define NavServicesAvailable()     (NavLibraryVersion != (void*)kUnresolvedCFragSymbolAddress)
  435. #endif
  436. #else
  437. pascal Boolean NavServicesAvailable();
  438. #endif
  439.  
  440.  
  441. #if PRAGMA_ALIGN_SUPPORTED
  442. #pragma options align=reset
  443. #endif
  444.  
  445. #if PRAGMA_IMPORT_SUPPORTED
  446. #pragma import off
  447. #endif
  448.  
  449. #ifdef __cplusplus
  450. }
  451. #endif
  452.  
  453. #endif /* __NAVIGATION__ */